the top of the each bar's stack is the one that will currently be displayed.
</para>
<para>
-Any messages added to a statusbar's stack must specify a <emphasis>context_id</emphasis>
-that is used to uniquely identify the source of a message. This context_id can be
-generated by gtk_statusbar_get_context_id(), given a message and the
-statusbar that it will be added to. Note that messages are stored in a
-stack, and when choosing which message to display, the stack structure is
-adhered to, regardless of the context identifier of a message.
+Any messages added to a statusbar's stack must specify a <emphasis>context
+id</emphasis> that is used to uniquely identify the source of a message.
+This context id can be generated by gtk_statusbar_get_context_id(), given a
+message and the statusbar that it will be added to. Note that messages are
+stored in a stack, and when choosing which message to display, the stack
+structure is adhered to, regardless of the context identifier of a message.
+</para>
+<para>
+One could say that a statusbar maintains one stack of messages for display
+purposes, but allows multiple message producers to maintain sub-stacks of
+the messages they produced (via context ids).
</para>
<para>
Status bars are created using gtk_statusbar_new().
Messages are added to the bar's stack with gtk_statusbar_push().
</para>
<para>
-The message at the top of the stack can be removed using gtk_statusbar_pop(). A message can be removed from anywhere in the stack if its message_id was recorded at the time it was added. This is done using gtk_statusbar_remove().
+The message at the top of the stack can be removed using gtk_statusbar_pop().
+A message can be removed from anywhere in the stack if its message_id was
+recorded at the time it was added. This is done using gtk_statusbar_remove().
</para>
<!-- ##### SECTION See_Also ##### -->
-<para>
-<variablelist>
-<varlistentry>
-<term>#GtkDialog</term>
-<listitem><para>another way of reporting information to the user.</para></listitem>
-</varlistentry>
-</variablelist>
-</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### STRUCT GtkStatusbar ##### -->
<para>
-Contains private data that should be modified with the functions described below.
+Contains private data that should be modified with the functions described
+below.
</para>
<!-- ##### SIGNAL GtkStatusbar::text-popped ##### -->
<para>
-Is emitted whenever a new message is popped off a statusbar's stack.
+
</para>
-@statusbar: the object which received the signal.
-@context_id: the context id of the relevant message/statusbar.
-@text: the message that was just popped.
+@statusbar:
+@context_id:
+@text:
<!-- ##### SIGNAL GtkStatusbar::text-pushed ##### -->
<para>
-Is emitted whenever a new message gets pushed onto a statusbar's stack.
+
</para>
-@statusbar: the object which received the signal.
-@context_id: the context id of the relevant message/statusbar.
-@text: the message that was pushed.
+@statusbar:
+@context_id:
+@text:
<!-- ##### ARG GtkStatusbar:has-resize-grip ##### -->
<para>
<!-- ##### FUNCTION gtk_statusbar_new ##### -->
<para>
-Creates a new #GtkStatusbar ready for messages.
+
</para>
-@Returns: the new #GtkStatusbar.
+@Returns:
<!-- ##### FUNCTION gtk_statusbar_get_context_id ##### -->
<para>
-Returns a new context identifier, given a description of the actual context.
+
</para>
-@statusbar: a #GtkStatusbar.
-@context_description: textual description of what context the new message is
-being used in.
-@Returns: an integer id.
+@statusbar:
+@context_description:
+@Returns:
<!-- ##### FUNCTION gtk_statusbar_push ##### -->
<para>
-Pushes a new message onto a statusbar's stack.
+
</para>
-@statusbar: a #GtkStatusbar.
-@context_id: the message's context id, as returned by
-gtk_statusbar_get_context_id().
-@text: the message to add to the statusbar.
-@Returns: the message's new message id for use with gtk_statusbar_remove().
+@statusbar:
+@context_id:
+@text:
+@Returns:
<!-- ##### FUNCTION gtk_statusbar_pop ##### -->
<para>
-Removes the message at the top of a #GtkStatusBar's stack.
+
</para>
-@statusbar: a #GtkStatusBar.
-@context_id: a context identifier.
+@statusbar:
+@context_id:
<!-- ##### FUNCTION gtk_statusbar_remove ##### -->
<para>
-Forces the removal of a message from a statusbar's stack. The exact @context_id and @message_id must be specified.
+
</para>
-@statusbar: a #GtkStatusBar.
-@context_id: a context identifier.
-@message_id: a message identifier, as returned by gtk_statusbar_push().
+@statusbar:
+@context_id:
+@message_id:
<!-- ##### FUNCTION gtk_statusbar_set_has_resize_grip ##### -->
<para>
-Sets whether the statusbar has a resize grip. %TRUE by default.
+
</para>
-@statusbar: a #GtkStatusBar.
-@setting: %TRUE to have a resize grip.
+@statusbar:
+@setting:
<!-- ##### FUNCTION gtk_statusbar_get_has_resize_grip ##### -->
<para>
-Returns whether the statusbar has a resize grip.
+
</para>
-@statusbar: a #GtkStatusBar.
-@Returns: %TRUE if the statusbar has a resize grip.
+@statusbar:
+@Returns:
P_("Whether the statusbar has a grip for resizing the toplevel"),
TRUE,
GTK_PARAM_READWRITE));
+
+ /**
+ * GtkStatusbar::text-pushed:
+ * @statusbar: the object which received the signal.
+ * @context_id: the context id of the relevant message/statusbar.
+ * @text: the message that was pushed.
+ *
+ * Is emitted whenever a new message gets pushed onto a statusbar's stack.
+ */
statusbar_signals[SIGNAL_TEXT_PUSHED] =
g_signal_new (I_("text_pushed"),
G_OBJECT_CLASS_TYPE (class),
G_TYPE_NONE, 2,
G_TYPE_UINT,
G_TYPE_STRING);
+
+ /**
+ * GtkStatusbar::text-popped:
+ * @statusbar: the object which received the signal.
+ * @context_id: the context id of the relevant message/statusbar.
+ * @text: the message that was just popped.
+ *
+ * Is emitted whenever a new message is popped off a statusbar's stack.
+ */
statusbar_signals[SIGNAL_TEXT_POPPED] =
g_signal_new (I_("text_popped"),
G_OBJECT_CLASS_TYPE (class),
statusbar->keys = NULL;
}
+/**
+ * gtk_statusbar_new:
+ *
+ * Creates a new #GtkStatusbar ready for messages.
+ *
+ * Returns: the new #GtkStatusbar
+ */
GtkWidget*
gtk_statusbar_new (void)
{
gtk_label_set_text (GTK_LABEL (statusbar->label), text);
}
+/**
+ * gtk_statusbar_get_context_id:
+ * @statusbar: a #GtkStatusbar
+ * @context_description: textual description of what context
+ * the new message is being used in
+ *
+ * Returns a new context identifier, given a description
+ * of the actual context. Note that the description is
+ * <emphasis>not</emphasis> shown in the UI.
+ *
+ * Returns: an integer id
+ */
guint
gtk_statusbar_get_context_id (GtkStatusbar *statusbar,
const gchar *context_description)
return *id;
}
+/**
+ * gtk_statusbar_push:
+ * @statusbar: a #GtkStatusbar
+ * @context_id: the message's context id, as returned by
+ * gtk_statusbar_get_context_id()
+ * @text: the message to add to the statusbar
+ *
+ * Pushes a new message onto a statusbar's stack.
+ *
+ * Returns: a message id that can be used with
+ * gtk_statusbar_remove().
+ */
guint
gtk_statusbar_push (GtkStatusbar *statusbar,
guint context_id,
return msg->message_id;
}
+/**
+ * gtk_statusbar_pop:
+ * @statusbar: a #GtkStatusBar
+ * @context_id: a context identifier
+ *
+ * Removes the first message in the #GtkStatusBar's stack
+ * with the given context id.
+ *
+ * Note that this may not change the displayed message, if
+ * the message at the top of the stack has a different
+ * context id.
+ */
void
gtk_statusbar_pop (GtkStatusbar *statusbar,
guint context_id)
msg ? msg->text : NULL);
}
+/**
+ * gtk_statusbar_remove:
+ * @statusbar: a #GtkStatusBar
+ * @context_id: a context identifier
+ * @message_id: a message identifier, as returned by gtk_statusbar_push()
+ *
+ * Forces the removal of a message from a statusbar's stack.
+ * The exact @context_id and @message_id must be specified.
+ */
void
gtk_statusbar_remove (GtkStatusbar *statusbar,
guint context_id,
}
}
+/**
+ * gtk_statusbar_set_has_resize_grip:
+ * @statusbar: a #GtkStatusBar
+ * @setting: %TRUE to have a resize grip
+ *
+ * Sets whether the statusbar has a resize grip.
+ * %TRUE by default.
+ */
void
gtk_statusbar_set_has_resize_grip (GtkStatusbar *statusbar,
gboolean setting)
}
}
+/**
+ * gtk_statusbar_get_has_resize_grip:
+ * @statusbar: a #GtkStatusBar
+ *
+ * Returns whether the statusbar has a resize grip.
+ *
+ * Returns: %TRUE if the statusbar has a resize grip.
+ */
gboolean
gtk_statusbar_get_has_resize_grip (GtkStatusbar *statusbar)
{
projects / gtk4.git / commitdiff